Why not append the bundle ID here?

• So that projects with combined documentation of multiple targets (when that lands) can share scripts between the documentation bundles of each target. I suspect that authors of packages with multiple targets will want scripts to be shared: nobody wants to set up their MathJax scripts once per target.
• In practice, even in documentation webpages for multiple targets, custom scripts loaded into the browser are global. For example, scripts that define the same global function can conflict with each other irrespective of the bundle they were loaded from. So namespacing the script files by bundle ID is moot.

(Also, if the relative path to the custom-scripts folder is always "/custom-scripts" then it’s easier to find it in the renderer code.)

I see. That's not how combined documentation works (which is already available as an experimental feature). Non-content files aren't automatically included in the combined archive. If this was treated as an asset, a collision between archives would be treated as an error. If this file is intended to be copied over into the combined archive, it should have an archive-unique prefix and this PR should update the merge command to copy over the expected files.

Hey David,

Sorry for the confusion; I hadn’t read your combined-documentation proposals yet and was operating under some admittedly hasty guesswork. Having read them now — the second, lower-level pitch in particular — I wasn't able to find more information on how combined documentation handles assets.

So I looked through the swift-docc code. But I haven't yet been able to find code for merging documentation archives, or for handling assets during that merge (the closest I could find was this, which seems related to merging assets of documentation archives given the phrasing here), or for including additional "non-symbol content for the landing page of the combined documentation" (a feature of docc merge you described in the technical pitch that could be relevant here). I'm definitely missing something obvious so apologies for the question, but where in the swift-docc codebase does documentation-archive merging happen? Essentially, I'm trying to figure out:

• How documentation-archive merging handles the theme-settings.json files of the archives being combined, so I can do the same to custom-scripts.json.
• How documentation-archive merging handles images, so I can do the same to the individual JS scripts in the archive's custom-scripts directory. (Assuming that doing so wouldn't break custom scripts, which I'll also look into.)

Thanks!!

• How documentation-archive merging handles the theme-settings.json files of the archives being combined, so I can do the same to custom-scripts.json.

The combined archive is assumed to want a consistent visual appearance across all its modules. Therefore it doesn't matter which theme-settings.json file it uses (but it only uses one of them).

• How documentation-archive merging handles images, so I can do the same to the individual JS scripts in the archive's custom-scripts directory. (Assuming that doing so wouldn't break custom scripts, which I'll also look into.)

In a regular archive, images are already located in a subdirectory named after the documentation's identifier. This makes merging images trivial because each subdirectory can simply be copied into the combined archives "images" directory.